The `serve` command starts a BAML-over-HTTP API server that exposes your BAML
functions via HTTP endpoints. This feature allows you to interact with your BAML
functions through a RESTful API interface.

## Usage

```
baml-cli serve [OPTIONS]
```

<Tip>
If you're actively developing, you can use the `dev` command to include
hot-reload functionality:
```
baml-cli dev [OPTIONS]
```

[See more](./dev)
</Tip>

## Options

| Option | Description | Default |
|--------|-------------|---------|
| `--from <PATH>` | Path to the `baml_src` directory | `./baml_src` |
| `--port <PORT>` | Port to expose BAML on | `2024` |
| `--no-version-check` | Generate `baml_client` without checking for version mismatch | `false` |

## Description

The `serve` command performs the following actions:

1. Exposes BAML functions as HTTP endpoints on the specified port.
2. Provides authentication middleware for secure access.

## Endpoints


`POST /call/:function_name`: Call a BAML function

```bash curl
curl \
  -X POST \
  "http://localhost:2024/call/MyFunctionName" \
  -H "Content-Type: application/json" \
  -d '{"arg1": "value1", "arg2": "value2"}'
```

`POST /stream/:function_name`: Stream results from a BAML function

```bash curl
curl \
  -X POST \
  "http://localhost:2024/stream/MyFunctionName" \
  -H "Content-Type: application/json" \
  -d '{"arg1": "value1", "arg2": "value2"}'
```

**Debugging**
- `GET /docs`: Interactive API documentation (Swagger UI)
- `GET /openapi.json`: OpenAPI specification for the BAML functions
- `GET /_debug/ping`: Health check endpoint
- `GET /_debug/status`: Server status and authentication check

## Stability

`baml-cli serve` is currently in Tier 2 stability. This means that the CLI and
the HTTP APIs are stable, but there are a number of features which are
not yet available:

   - the [TypeBuilder API](/ref/baml_client/type-builder)
   - the [Collector API](/guide/baml-advanced/collector-track-tokens)
   - the [Modular API](/guide/baml-advanced/modular-api)
   - custom trace annotations for [Boundary Studio](/guide/boundary-cloud/observability/tracking-usage)

## Authentication

We support the header: `x-baml-api-key`

Set the `BAML_PASSWORD` environment variable to enable authentication.

## Examples

1. Start the server with default settings:
   ```
   baml-cli serve --preview
   ```

2. Start the server with a custom source directory and port:
   ```
   baml-cli serve --from /path/to/my/baml_src --port 3000 --preview
   ```

## Testing

To test the server, you can use the following `curl` commands:

1. Check if the server is running:
   ```bash
   curl http://localhost:2024/_debug/ping
   ```

2. Call a function:
   ```bash
   curl -X POST \
      http://localhost:2024/call/MyFunctionName \
      -H "Content-Type: application/json" \
      -d '{"arg1": "value1", "arg2": "value2"}'
   ```

   ```bash API Key
   curl -X POST \
      http://localhost:2024/call/MyFunctionName \
      -H "Content-Type: application/json" \
      -H "x-baml-api-key: ${BAML_PASSWORD}" \
      -d '{"arg1": "value1", "arg2": "value2"}'
   ```

3. Access the API documentation:
   Open `http://localhost:2024/docs` in your web browser.
